home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 November: Tool Chest / Dev.CD Nov 98 TC.toast / Sample Code / QuickDraw / OffSample / Offscreen.p < prev    next >
Encoding:
Text File  |  1994-11-18  |  7.5 KB  |  228 lines  |  [TEXT/MPS ]
  1. {------------------------------------------------------------------------------
  2. #
  3. #    Apple Macintosh Developer Technical Support
  4. #
  5. #    "Skippy White's Famous High Level Off-Screen Map Routines”
  6. #
  7. #    Offscreen.p        -    Pascal Header
  8. #
  9. #    Copyright © 1989 Apple Computer, Inc.
  10. #    All rights reserved.
  11. #    The characters depicted herein (except Skippy White) are fictitious.
  12. #
  13. #    Versions:    
  14. #                1.00                04/89
  15. #                1.01                06/92
  16. #
  17. #    Components:
  18. #                Offscreen.p            April 1, 1988
  19. #                Offscreen.inc1.p    April 1, 1988
  20. #
  21. #    These routines provide a high-level interface to the QuickDraw & Color
  22. #    Manager routines which allow the creation and manipulation of off-screen
  23. #    bitmaps and pixmaps. They are designed to run on any machine with 128K or
  24. #    later ROMs (sorry 64K ROM fans).
  25. #    Note that the design incorporates the idea that you can go along pretending
  26. #    there is an offscreen buffer even when one couldn’t be allocated, and the
  27. #    calls will do nothing.
  28. #
  29. -------------------------------------------------------------------------------}
  30.  
  31. UNIT Offscreen;
  32.  
  33.  
  34. INTERFACE
  35.  
  36.  
  37.  
  38.     USES Types, QuickDraw, Events, Controls, Windows, TextEdit, Dialogs, Fonts, Lists,
  39.     Menus, Resources, Scrap, ToolUtils, 
  40.     OSUtils, Files, Devices, DeskBus, DiskInit, Disks, Errors, Memory, Retrace, SegLoad, Serial,
  41.     ShutDown, Slots, Sound, Start, Timer;
  42.  
  43.  
  44.  
  45. CONST
  46.     noDeviceIntersectErr = -6969;
  47.  
  48.     kMaxDepth = 0;
  49.     
  50.     kOffscreenReserve = 8196;
  51.  
  52.  
  53. {Must be called before any routines of the unit are used.}
  54.  
  55. PROCEDURE InitOffscreen;
  56.  
  57.  
  58.  
  59. {Create an off-screen pixel map for drawing into and then bltting elsewhere.}
  60.  
  61. FUNCTION NewOffscreen(bounds: Rect; depth: INTEGER; colors: CTabHandle;
  62.                       memoryPolite: BOOLEAN; VAR buffNotNeeded: BOOLEAN; VAR offscreenHandle: Handle): OSErr;
  63.  
  64. {    Memory Manager errors may occur. In addition, if the requested depth is
  65.     not supported by QuickDraw, memFullErr will be returned.
  66.  
  67.     bounds:
  68.         The bounds rectangle to be used for the pixmap (in global coordinates).
  69.     This will often be the same as the bounding rectangle of a port or window
  70.     to be used. It must be in global coordinates, however, so you can't (directly)
  71.     use a window's portRect.
  72.  
  73.     The bounds will be offset so that topLeft is at (0, 0) before setting up the
  74.     off-screen port. The global version will be stored as the requested bounds,
  75.     and updated by calls to MoveOffscreen.
  76.  
  77.         NOTE: if you'll pass in a depth > 0, you can use a "local" boundsRect.
  78.  
  79.     depth:
  80.         The desired pixel depth of the map. Use kMaxDepth (0) if you want the
  81.     maximum depth device for the (global) bounds rectangle.
  82.  
  83.     colors: (only applies if depth > 0; ignored otherwise)
  84.         The color table you want the off-screen pixmap to have. If you pass in NIL
  85.     the color table from the System or ROM (for that depth) will be used.
  86.  
  87.     memoryPolite:
  88.         If true, the bits will be kept in a purgeable block. If it gets purged, then
  89.     CheckOffscreen or CheckBoundsOffscreen will reallocate it and a redraw will be needed.
  90.  
  91.     offscreenHandle:
  92.         The new handle to the (private) data is returned in offscreenHandle.
  93.  
  94.     A new graphics device will be created if requestedDepth > 0. NewHandle will
  95.     be used to allocate storage for the actual pixels.
  96. }
  97.  
  98.  
  99.  
  100. {Dispose of the entire off-screen data structure.}
  101.  
  102. PROCEDURE DisposeOffscreen(offscreenHandle: Handle);
  103.  
  104.  
  105.  
  106. {Prepare to draw to an off-screen port and map. The port and handle to the bits
  107.  will be locked down. If you don’t have a specific port you want to use, pass
  108.  in NIL for port and the private one for this buffer will be used.
  109.  Although you can use this for a buffered window and pass in the WindowPtr,
  110.  you would normally use BeginUpdateOffscreen instead (see below).}
  111.  
  112. PROCEDURE BeginOffscreenDrawing(offscreenHandle: Handle; port: GrafPtr);
  113.  
  114.  
  115.  
  116. {Call this when through drawing to the off-screen map. Must match a previous
  117.  StartDO call, of course. }
  118.  
  119. PROCEDURE EndOffscreenDrawing(offscreenHandle: Handle);
  120.  
  121.  
  122.  
  123. {Check to see if the depth or color table of the principal graphic device
  124.  associated with the bits has changed. Call this when you get an update event
  125.  that relates to this buffer, and if you have some idle time and want to redraw
  126.  any part of the offscreen map that is invalid.
  127.  
  128.  For buffered windows, call this right before you call BeginUpdateOffscreen; don’t
  129.  skip the Begin- EndUpdateOffscreen stuff even if drawNeeded returns FALSE.
  130.  
  131.  drawNeeded will return TRUE if you need to redraw the contents of the map.
  132.  The result, if <> noErr, will usually be a Memory Manager error indicating that
  133.  the block of bits for a new (greater) depth couldn't be allocated.}
  134.  
  135. FUNCTION CheckOffscreen(offscreenHandle: Handle; VAR drawNeeded: BOOLEAN): OSErr;
  136.  
  137.  
  138.  
  139. {Call this when the rectangle of the off-screen map needs to change, perhaps
  140.  due to a window moving on the main screen. This will also check for any change
  141.  in depth.
  142.  drawNeeded will return TRUE if you need to redraw the contents of the map.
  143.  The result, if <> noErr, will usually be a Memory Manager error indicating that
  144.  the block of bits for a new (greater) size (or depth) couldn't be allocated.}
  145.  
  146. FUNCTION CheckBoundsOffscreen(offscreenHandle: Handle; newBounds: Rect;
  147.                        VAR drawNeeded: BOOLEAN): OSErr;
  148.  
  149.  
  150.  
  151. {When buffering the contents of a window, use this instead of ValidRect.
  152.  If offscreenHandle isn’t a buffer for a window, pass in NIL for the window parameter.}
  153.  
  154. PROCEDURE ValidRectOffscreen(offscreenHandle: Handle; window: WindowPtr; validRect: Rect);
  155.  
  156.  
  157.  
  158. {When buffering the contents of a window, use this instead of ValidRgn.
  159.  If offscreenHandle isn’t a buffer for a window, pass in NIL for the window parameter.}
  160.  
  161. PROCEDURE ValidRgnOffscreen(offscreenHandle: Handle; window: WindowPtr; validRegion: RgnHandle);
  162.  
  163.  
  164.  
  165. {When buffering the contents of a window, use this instead of InvalRect.
  166.  If offscreenHandle isn’t a buffer for a window, pass in NIL for the window parameter.}
  167.  
  168. PROCEDURE InvalRectOffscreen(offscreenHandle: Handle; window: WindowPtr; invalidRect: Rect);
  169.  
  170.  
  171.  
  172. {When buffering the contents of a window, use this instead of InvalRgn.
  173.  If offscreenHandle isn’t a buffer for a window, pass in NIL for the window parameter.}
  174.  
  175. PROCEDURE InvalRgnOffscreen(offscreenHandle: Handle; window: WindowPtr; invalidRgn: RgnHandle);
  176.  
  177.  
  178.  
  179. {Get a map pointer, suitable for CopyBits. Note that neither the map
  180.  itself, nor the bits pointed to are locked down. Thus this map, and
  181.  the bits pointed to by GetMap^.baseAddr will move. Also note that this
  182.  will be a BitMapPtr for Classic QD systems, and will be a PixMapPtr
  183.  for Color QD systems. NIL will be returned if there are no bits. It
  184.  may be possible to re-allocate them with CheckOffscreen.}
  185.  
  186. FUNCTION GetMap(offscreenHandle: Handle): BitMapPtr;
  187.  
  188.  
  189.  
  190. {Returns a handle to the bits. NIL means either that it got purged, or
  191.  that the bits aren’t in a heap block after all.}
  192.  
  193. FUNCTION GetBitsHandle(offscreenHandle: Handle): Handle;
  194.  
  195.  
  196.  
  197. {---------- Here are routines specific to buffered windows ----------}
  198.     
  199.  
  200. {Create an off-screen pixel map for a port.
  201.  It will always use kMaxDepth and always be memoryPolite (???and shouldn’t return buffNotNeeded?).}
  202.  
  203. FUNCTION NewOffscreenForWindow(window: WindowPtr; VAR buffNotNeeded: BOOLEAN;
  204.                                VAR offscreenHandle: Handle): OSErr;
  205.  
  206.  
  207.  
  208. {When buffering a window you should use this instead of BeginUpdate. The visRgn
  209.  will be setup properly. window must be a valid window (don’t pass in NIL).
  210.  Call EndUpdateOffscreen when you are through drawing.}
  211.  
  212. PROCEDURE BeginUpdateOffscreen(offscreenHandle: Handle; window: WindowPtr);
  213.  
  214.  
  215.  
  216. {The sequence is BeginUpdateOffscreen, draw, EndUpdateOffscreen}
  217.  
  218. PROCEDURE EndUpdateOffscreen(offscreenHandle: Handle; window: WindowPtr);
  219.  
  220.  
  221.  
  222.  
  223. IMPLEMENTATION
  224.  
  225. {$I Offscreen.inc1.p}
  226.  
  227. END.
  228.